API Reference
Introduction
The Covalent API facilitates the design and implementation of a large variety of loyalty program use cases for our clients. Generally, we will implement programs directly. These API docs are intended to give a sense of the API end points that our clients call to build into thier warehouse and customer facing environment. Our API allows our Partners to:
- Issue, Transfer, Redeem, or Exchange their loyalty currency via API
- Pull Transaction History Details
To benefit from the Covalent platform, you do not need to use all of these features. While there are many Endpoints for specific use cases, most clients end up using only a few Endpoints.
Architecture
The Covalent API is organized around REST. Our API has predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.
Calls to the API have to be properly authenticated using your public and secret API keys. We will facilitate your access to these keys.
The API is designed for a server to server communication. If you want to communicate with the API from a client it must be through a server environment, to protect the integrity of the requests and the API keys, and not expose them on front-end platforms.
Authentication
The API authenticates every request based on two elements - Credential and Signature. Every request must include an Authorization header with the following two elements.
Credential=<public-key>, Signature=<calculated-signature>
Credential
In this parameter, the API requires you to provide the <public-key> that is unique to your account.
Signature
How is the Signature calculated?
The signature is a HMAC-SHA256 hash in hexadecimal of the request content, using the private_key as the key.
Keep in mind that the string you use to generate the signature and the string you send to the API has to be exactly the same. This includes newlines and spaces. If you compress the JSON body of your request, after generating the signature, the request will be rejected.
POST/PUT/PATCH HTTP methods
These types of requests use the string representation of the body to calculate the signature.
For example, for the request with body: {"foo": "bar"} the signature calculated using sec_12345 as the private key would be 4d84ba663b9c6179dd98023087da5baa8a4e3eb59ba45284935261350ba70742
GET HTTP method
This type of request uses the query string to calculate the signature. Take into account that the "?" character must not be included while calculating the signature.
For example, for the request with query string: ?foo=bar the signature calculated using sec_12345 as the private key would be 88d64dfcb542c35dc22bae059bd5f5a5d038572a7b391dfc4cd5f3a5530c1760 which is the hash for the string "foo=bar"
To generate the signature of a GET request without any parameters, simply encode an empty string.
# Security The API uses asymmetric cryptography to authenticate requests using the API keys we provide. This provides the following assurances: - **Requester identification:** Every request requires your public key to be sent, in conjunction with a signature generated with your secret key. - **Protection against man-in-the-middle (MITM) attacks:** The request signature is calculated using the body of the request, which means that any request that has been tampered with during the transport will be rejected by the Covalent platform, since the signature received will not match the request contents.
The API only supports requests over HTTPS.
# Idempotency The API supports [idempotent](https://en.wikipedia.org/wiki/Idempotence) requests to safely retry requests without having to worry about doing the same operation more than once. For example, if there's a connection error generating a gift card, you can retry the request with the same idempotency key without having to worry about creating multiple gift cards.
To send an idempotent request, include an additional Idempotency-Key: <key> header in the request. An Idempotency Key <key> is a unique identifier generated by the client with a length between 1 and 255 characters. While this can be any type of unique key, we recommend a UUID to avoid collisions. An Idempotency key expires 8 hours after the initial request.
In a repeated request the response will always have the response body of the original request, along with the same status and 400 errors, if any. The response will also include the header Idempotency-Repeated: true. In the rare instances where a request is repeated while the first one has not been completed yet, the API will respond with a 409 - Conflict status.
The API supports idempotency on POST and PATCH requests. Since GET, PUT and DELETE are idempotent by default, the Idempotency-Key header will be ignored.
# Key fields Covalent acts as a connectivity bridge between various partners using its standardized APIs and interface, hence, shielding each partner from the complexity, nuances, and customizations of hundreds of loyalty systems and merchant partners. However, the interacting partners need to have a common reference for a transaction in their own system for easy reconciliation as well as for customer support purposes. In this section, you will find information on some key fields and attributes that are used through our API and on different objects. This information will help you understand how to use these key fields.
External Reference
The field external_reference is used for each transaction request to provide a unique identifier from your system that can be used as a reference during the reconciliation process. This could be a GUID, internal transaction identifier, invoice number, booking number, itinerary number, or any other unique number in your system that can be used to uniquely identify the action. Even though this is not a required field, it is strongly recommended that you provide value in this field.
Loyalty System Id
The field loyalty_system_id is returned by our system on each transaction and it provides the unique identifier in the partner loyalty system. This ID is not generated by Covalent but is provided by the partner loyalty program and hence could be used as a common field for reconciliation between your system and the partner's system.
Loyalty System Data
Sometimes, a loyalty program requires you to send some additional data to connect. For example, user_id, application_id, partner_code, etc. You will be able to provide the data in this field for all the transactions with the partner loyalty program. To check if and what additional data is required by the partner loyalty program, refer to the Partners Endpoint.
Common Use cases
Our API can be used for numerous Loyalty Commerce use cases. Some of the most common use cases are mentioned below along with the information on which Endpoints to use for each use case. There are auxiliary Endpoints that could be used to enhance your integration and customer experience. For example, you could pull all transaction history out via the API into your Business Intelligence or data staging environments or you could validate the member details before issuing Loyalty Currency Units.
Accrual/Issue/Top-up
The underlying objective of this use case is to “give Loyalty Currency Units to a member” for one reason or another. The reason could be a purchase of a product, their birthday, completion of a survey, referral, customer service issue, etc. Furthermore, you may want to give the member units of your own Loyalty Currency or one of your Partners’ Loyalty Currency.
You should use Accruals Endpoints for this use case. There are three Endpoints that can be used for issuing your or a Partner’s currency. You can use any one of the Endpoints or a combination of them to issue Loyalty Currency Units to the member.
Direct Accruals
This Endpoint is to be used when you know the exact number of Loyalty Currency Units to give to a member. In this scenario, you are calculating the number of Loyalty Currency Units in your environment and providing the exact number of units in the endpoint.
Purchase Rules
This Endpoint is to be used when you would like to give the number of Loyalty Currency Units based on Purchase Rule(s) defined in the Covalent system. For example, giving points worth 1% of the fiat transaction amount. In this case, your application does not need to know how to calculate the number of Loyalty Currency Units or even the cost of the Loyalty Currency Units in any of your Partners' programs.
Activity Rules
This Endpoint is to be used when you would like to issue the number of Loyalty Currency Units based on pre-defined Activity Rule(s) in the system. For example, you might offer 200 points for posting a product review or referring a friend.
Currency Exchange
Our API provides tools for quick collaboration among brands to enable their respective members to exchange loyalty units between programs. The exchange could be one-way only, or both directions – in and out – of the programs. Use the Loyalty Currency Exchange Endpoints to implement this use case. There are 2 Endpoints that can be used to enable exchange between partners.
Simulate an exchange
This Endpoint allows you to simulate how many Loyalty Currency units the member would receive of a Partner’s Loyalty Currency in exchange. This can be used to show the member how many points in one or more programs they could get if completing the exchange.
Execute an exchange
This Endpoint allows you to comlete the exchange Loyalty Currency units to the Partner’s Loyalty Currency.
Tip: You could use the Partners Endpoints to get the list of Exchange Partners and automatically display the fields required for each program to complete the exchange. This will be necessary for loyalty programs that require more member validation fields than just the membership number.
Redemption/Pay with Points
Our Redemption Endpoints have standardized the redemption process across various types of loyalty programs and underlying loyalty systems. This shields you from needing to understand the underlying complexity to integrate into a new loyalty system or modifying the existing integration for a different set of parameters for a new partner.
You should use Standard Redemption Endpoints for this use case. There are four Endpoints that can be used for allowing a Partner’s Loyalty Currency as a form of payment. You can use any one of the Endpoints or a combination of them depending on your customer journey. Although not necessary, we highly recommend you use the “Lookup a Member” Endpoint to validate if the member exists and if they have enough balance to complete the payment before submitting the payment transaction.
Strictly speaking, Loyalty Exchange and Exchange for Gift Cards are also redemptions, but we provide explicit Endpoints for those actions due to the very high occurrence of those use cases in the industry. Standard Redemptions refers to any other redemptions where the Partners have allowed the member to redeem (exchange) their Loyalty Currency Units for your Products and Services. The products and services may range from flower delivery to booking a trip, buying an insurance plan, topping up their mobile plan, paying at a restaurant, buying concert tickets, or even applying points toward the purchase of a car.
Simulate a Redemption
To simulate the redemption action and provide information to the member such as the number of points required to complete the action, cancellation allowed, etc. without actually deducting the points from their balance or completing the transaction.
Execute a Redemption
Deduct points from the member’s account in exchange for the product or service offered.
Adjust a Redemption
If allowed by the Partner, you may use this Endpoint to notify of any modification in an already completed Redemption. The system will automatically identify if more points are to be redeemed or points are to be refunded to the member.
Cancel a Redemption
If allowed by the Partner, you may use this Endpoint to cancel an already completed Redemption to refund the points.
What made this section unhelpful for you?
Base URL
Production:
https://api.loyaltyboomerang.com/public/v3.0
Sandbox:
https://sandbox.api.loyaltyboomerang.com/public/v3.0
What made this section unhelpful for you?
Direct Accruals
Direct Accruals Endpoint is to be used in the scenarios where you know in advance the exact number of loyalty currency units that are to be issued to a member and from which account if multiple accounts are available.
Purchase Rules
The Purchase Endpoints allows you to simulate or execute a purchase rule to issue loyalty currency units to your members. The purchase loyalty rules can be defined in the following section in the Management Dashboard:
Loyalty Rules > Purchase Rules
Activity Rules
The Activities Endpoints allows you to simulate or execute an activity rule to issue loyalty currency units to your members. The activity loyalty rules can be defined in the following section in the Management Dashboard:
Loyalty Rules > Activity Rules
Exchanges
The Exchange Endpoints enables you to allow your members to exchange their Loyalty Currency Units with your partners' Loyalty Currency Units. You can have a different Exchange Partnership with each Exchange Partner, where you could allow exchange IN or OUT of your currency. The exchange price and other settings are established during the Exchange Partnership set up in the Management Dashboard.
Note that the currencies to be exchanged could be present in different regions and fiat currencies. Covalent will do the currency conversion for the fiat currencies based on the mid-day exchange rate between the fiat currencies.
Members
Member Endpoints can be used to create a new member, look up information on a member, retrieve a member's details to your system, or update any member's details. Only the Currency Owner i.e. the loyalty program to which the member belongs has access to create a member or update a member.
The Partners could look up a member to confirm if the member exists, check the member account balance, or other details of the member record based on permissions granted by the Currency Owner.
Covalent has standardized these Endpoints and orchestrates the calls to various Loyalty programs to validate a member, get member details, etc. if the Covalent platform is not the primary data store for the relevant loyalty program.
The Member object
The Member Object represents a member record. For the loyalty programs where Covalent is not the primary data store for their members, the system will connect with the loyalty program system to fetch the member information and present it in the following format.
Conversions
Standard Redemptions
Redemptions are referred to as any action that allows the members to redeem the value of their Loyalty Currency Units in exchange for any product, services, or any other redemption options. Standard Redemption Endpoints provides a standardized way for you to allow members to redeem their Loyalty Currency Units for any type of product or service that is not a Gift Card or an Exchange into another loyalty program’s Loyalty Currency.
Standard Redemptions are any redemptions where the Partners have allowed the member to redeem (exchange) their Loyalty Currency Units for your Products and Services. The products and services may range from flower delivery to booking a trip, buying an insurance plan, topping up their mobile plan, paying at a restaurant, buying concert tickets, or even applying points toward the purchase of a car.
The Partners define in the Partnership Settings that the members can redeem their points in various product and service categories. Thus, it is very important that you provide information about the product and services in the request message. If you don’t have defined product categories and details, simply send “General” in the 'category' field.
Some Partners may allow an option to cancel or modify the redemption. This information is provided in the response messages of the Endpoints for you to inform the member before completing the redemption.
Gift Cards
These Endpoints are used for redemption via Gift cards. These Endpoints could be used to retrieve a particular Gift Card, to retrieve a list of enabled Gift cards, to simulate an exchange of currency units for a Gift card, to exchange currency units for a Gift card, or to redeem a custom Gift card. The gift card exchange feature for the loyalty currency must be enabled in the following section of the Management Dashboard: Redemptions > Gift Card Management
There are two objects in the system that represent a Gift card - GiftCard Object and GiftCardCode Object. GiftCard Object represents the general characteristics of the Gift card whereas GiftCardCode Object represents the characteristics that are specific to the Gift card issued to a member.
For example, if a currency owner enables Starbucks gift card through the Management Dashboard there will be a GiftCard Object in our system that would represent general details of Starbucks cards including the possible denominations of let's say $5, $10, $15, $25. When a member exchanges their points for a Starbucks gift card, the system will create a GiftCardCode object specific for that member with specific information such as the value of the Gift card ($5).
The Gift Card object
GiftCard Object represents a Gift card that could be used for redemption of Loyalty Currency units via Gift cards. It contains the details of the general characteristics of the Gift card. Note that it doesn't represent an issues/redeemed Gift card but only the general characteristics. Once a Gift card is issued GiftCardCode Object provides the details specific to the Gift card for the member. It has the following attributes:
The Gift Card Code object
GiftCardCode Object represents the code details for the issued Gift card. It contains information specific to the Gift card issued to the member. For example, in general, Starbucks Gift cards could be of any one of denominations of $5, $10, $25, $50. This Object will provide the exact amount of the Gift card that was issued to the user. It has the following attributes:
Transactions
All actions in the system that result in the movement of any Loyalty Currency are represented by a unique Transaction object. E.g. some of the actions are:
- Creation of Loyalty Currency units
- Purchase of partner's Loyalty Currency units
- Issuance or transfer of Loyalty Currency to a member, partner, or other accounts
- Exchange of Loyalty Currency units to another Loyalty Currency
- Redemption of Loyalty Currency units to gift cards or other products
Transaction Endpoints can be used to create a transaction, retrieve information of a transaction, all transactions of a member, or all transactions related to your account. These Endpoints can also be used to cancel or update a transaction.
NOTE: Create a Transaction CANNOT be used to do accruals and redemptions, including Gift Cards and Currency Exchange. Use Accruals and Redemptions Endpoints for such actions; the system will automatically create the underlying required transaction.
The Transaction object
What made this section unhelpful for you?
List a member's transactions
This Endpoint allows you to retrieve the details of all the transactions of the specified member. To retrieve information about a specific transaction, use 'Retrieve a transaction' Endpoint.
Query Parameters
Provide value to retrieve the exact page of results. If no value is provided, the system will return the first page.
Provide a value between 1 to 500 to return the number of result items on each page.
Provide the date range, in the format of two dates separated by a comma, to filter the items based on when when they were created. The first value is the starting date and the second value is the end date. The end date is optional if you want to retrieve all the items since the starting date.
Provide value to filter transactions by status. Multiple values are accepted, separated by commas.
adjustedcancelledcompletedpendingpending_external_approvalrejectedreversedProvide value to filter transactions by type. Multiple values are accepted, separated by commas.
accrualgift_card_exchangeloyalty_currency_expirationloyalty_currency_generationloyalty_currency_purchaseloyalty_currency_withdrawalmember_exchangeredemptionreversaltransfer... 1 other enums
Body Parameters
This parameter requires you to send the loyalty_program_identifiers of the member. Each Loyalty Program may have a different set of identifiers that together uniquely identifies a member. For example, one loyalty program may only require the membership id but another loyalty program may require a combination of membership id and last name.
Show child attributes
This unique identifier represents the loyalty program currency to which the member belongs. It is a unique shortcode Identifier assigned by the system to each loyalty currency. It can be found in the 'My Currency' section under the 'About My Currency' screen in the Management Dashboard. For the Currency Identifier of your partners' currencies refer to the Currency Symbol field in the 'My Partners' section in the Management Dashboard or Endpoints to obtain Partners' information.
Response
Response Attributes
Total number of items returned.
GET parameter for the previous page.
Refer to Transaction Object for details on each child attribute
Show child attributes
What made this section unhelpful for you?
Response
{
"count": 10,
"previous": "",
"results": [
{
"amount": 250,
"completed_at": "2019-03-04T11:50:03+0000",
"created_at": "2019-03-04T11:50:03+0000",
"destination_account": {
"id": "acc_abc123",
"owner": {
"id": "mp_abc123",
"type": "partner"
}
},
"external_reference": "",
"id": "tx_abc12312345",
"loyalty_system_data": {},
"loyalty_system_id": "",
"loyalty_currency": "LLL",
"metadata": {
"foo": "bar"
},
"origin_account": {
"id": "acc_abc123",
"owner": {
"id": "mp_abc123",
"type": "partner"
}
},
"reason": "present",
"reason_code": "",
"related_data": "",
"release_date": "2447-12-01T21:56:57Z",
"status": "pending",
"status_message": "The release date has not been reached.",
"status_message_code": "release_date_not_reached",
"sub-type": "activity_rule",
"type": "transfer"
}
]
}What made this section unhelpful for you?
List transactions
This Endpoint allows you to retrieve the details of all the transactions. To retrieve information about a specific transaction, use 'Retrieve a transaction' Endpoint.
Query Parameters
Provide value to retrieve the exact page of results. If no value is provided, the system will return the first page.
Provide a value between 1 to 500 to return the number of result items on each page.
Provide the date range, in the format of two dates separated by a comma, to filter the items based on when when they were created. The first value is the starting date and the second value is the end date. The end date is optional if you want to retrieve all the items since the starting date.
Provide value to filter transactions by status. Multiple values are accepted, separated by commas.
adjustedcancelledcompletedpendingpending_external_approvalrejectedreversedProvide value to filter transactions by type. Multiple values are accepted, separated by commas.
accrualgift_card_exchangeloyalty_currency_expirationloyalty_currency_generationloyalty_currency_purchaseloyalty_currency_withdrawalmember_exchangeredemptionreversaltransfer... 1 other enums
Response
Response Attributes
Total number of items returned.
GET parameter for the previous page.
Refer to Transaction Object for details on each child attribute
Show child attributes
What made this section unhelpful for you?
Response
{
"count": 10,
"previous": "",
"results": [
{
"amount": 250,
"completed_at": "2019-03-04T11:50:03+0000",
"created_at": "2019-03-04T11:50:03+0000",
"destination_account": {
"id": "acc_abc123",
"owner": {
"id": "mp_abc123",
"type": "partner"
}
},
"external_reference": "",
"id": "tx_abc12312345",
"loyalty_system_data": {},
"loyalty_system_id": "",
"loyalty_currency": "LLL",
"metadata": {
"foo": "bar"
},
"origin_account": {
"id": "acc_abc123",
"owner": {
"id": "mp_abc123",
"type": "partner"
}
},
"reason": "present",
"reason_code": "",
"related_data": "",
"release_date": "2447-12-01T21:56:57Z",
"status": "pending",
"status_message": "The release date has not been reached.",
"status_message_code": "release_date_not_reached",
"sub-type": "activity_rule",
"type": "transfer"
}
]
}What made this section unhelpful for you?
Create a transaction
This Endpoint allows you to create a transaction in the system. This Endpoint should ONLY be used for transaction types of "transfer" such as from a member to another member, from one partner account to another partner account, or transfer between your own accounts. This Endpoint should NOT be used for issuing Currency to members, exchanging loyalty currencies, redeeming Gift Cards, or other redemptions. Relevant Endpoints (Accruals and Redemptions) should be used for the corresponding use cases.
Body Parameters
The transaction amount in units of the Loyalty Currency
The destination for the transaction i.e. who is receiving the loyalty currency units. Depending on the type of transaction, it could either be a member or a partner account.
In case of transferring units to a partner account, provide the Account ID as a string input. You could also send the Partner ID in this field. In the latter case, the system will automatically select the default account associated with the Partner ID.
In case of transferring units from a member – ...
A unique identifier from your system that can be used as a reference during the reconciliation process. This could be a GUID, internal transaction identifier, invoice number, booking number, itinerary number, or any other unique number in your system that can be used to uniquely identify the action. Even though this is not a required field, it is strongly recommended that you provide value in this field.
This unique identifier represents the loyalty program currency to which the member belongs. It is a unique shortcode Identifier assigned by the system to each loyalty currency. It can be found in the 'My Currency' section under the 'About My Currency' screen in the Management Dashboard. For the Currency Identifier of your partners' currencies refer to the Currency Symbol field in the 'My Partners' section in the Management Dashboard or Endpoints to obtain Partners' information.
This parameter requires you to send additional information to connect to the loyalty program. For example, user_id, application_id, partner_code, etc. The Partners Endpoint provides the details on which data fields are mandatory inside this parameter.
Allows up to 5 levels of nesting depth. This data content can include information about the purchase such as items included, information about the store, information about the member, or anything else that could be helpful for analytics and reporting.
Show child attributes
Textual description for why the transaction was created. This text is presented to the origin and destination account holders in their transaction history. While any string length is accepted, 26 characters or less is typically optimal to explain to the member in their transaction history why this transaction was created.
The origin for the transaction i.e. who is issuing or providing the loyalty currency units. Depending on the type of transaction, it could either be a member or a partner account.
In case of transferring units from a partner account, provide the Account ID as a string input. You could also send the Partner ID in this field. In the latter case, the system will automatically select the default account associated with the Partner ID.
In case of transferring units from a m...
Reason code for why the transaction was created. This field is used for reporting purposes if the ‘reason’ field is dynamic and can vary within one category of transactions.
bonus_rewardcustomer_service_issuegiftlottery_rewardotherparticipation_check_in_rewardproduct_purchasereferral_rewardservice_purchasesharing_information_reward... 2 other enums
Response
Response Attributes
The transaction amount in the Loyalty Currency Units
The date and time when this transaction was completed based on the status and release date.
The date and time when this transaction was created. Note that it could be different from when the transaction is completed based on the status and release date.
Represents an account in the system.
Show child attributes
A unique identifier that can be used as a reference to uniquely identify the action in your system.
Unique internal identifier generated by the system for each Transaction.
This parameter requires you to send additional information to connect to the loyalty program. For example, user_id, application_id, partner_code, etc. The Partners Endpoint provides the details on which data fields are mandatory inside this parameter.
Unique transaction identifier provided by the loyalty system.
This unique identifier represents the loyalty program currency to which the member belongs. It is a unique shortcode Identifier assigned by the system to each loyalty currency. It can be found in the 'My Currency' section under the 'About My Currency' screen in the Management Dashboard. For the Currency Identifier of your partners' currencies refer to the Currency Symbol field in the 'My Partners' section in the Management Dashboard or Endpoints to obtain Partners information..
Allows up to 5 levels of nesting depth. This data content can include information about the purchase such as items included, information about the store, information about the member, or anything else that could be helpful for analytics and reporting.
Show child attributes
Represents an account in the system.
Show child attributes
The textual description for why the transaction was created. This text is presented to the origin and destination account holders in their transaction history. While any string length is accepted, 26 characters or less is typically optimal to explain to the member in their transaction history why this transaction was created.
Reason code for why the transaction was created. This field is used for reporting purposes if the ‘reason’ field is dynamic and can vary within one category of transactions.
This provides data about the related action that created the transaction. Actions could be the execution of transaction rule(s), activity rule(s), or a redemption. It is different from Metadata field because Metadata is additional optional information whereas this field is mandatory for certain actions such as Purchase rule, Activity rule, and Redemptions.
Future date on which the Loyalty Currency Units should be made available to the member. The Loyalty Currency Units would be reserved for the member but not made available till the release date is reached. This is used in scenarios such as hotel bookings or flight purchases that are done before the trip so that the member doesn’t redeem the points until they’ve actually stayed at the hotel or flown in the booked flight.
Provides the current status of the transaction. Transactions executed completely have the status set to completed. Refer to the fields status_message_code and status_message for further information if the transaction status is anything other than completed.
adjustedcancelledcompletedpendingpending_external_approvalrejectedreversedThe detailed reason why the transaction is not in the completed status. This field will be null if the transaction status is completed.
The code representing the details about the transaction status when the transaction status is not completed. This field will be null if the transaction status is completed.
release_date_not_reachedpending_external_approvalmember_does_not_existThis field provides further granular information about certain types of transactions.
activity_ruleadjustment_decreaseadjustment_increasebuycancellationinmembermember_to_memberotherout... 5 other enums
A transaction will always have a type associated with it.
accrualgift_card_exchangeloyalty_currency_expirationloyalty_currency_generationloyalty_currency_purchaseloyalty_currency_withdrawalmember_exchangeredemptiontransferreversal... 1 other enums
Response Attributes
Show child attributes
What made this section unhelpful for you?
Response
{
"amount": 250,
"completed_at": "2019-03-04T11:50:03+0000",
"created_at": "2019-03-04T11:50:03+0000",
"destination_account": {
"id": "acc_abc123",
"owner": {
"id": "mp_abc123",
"type": "partner"
}
},
"external_reference": "",
"id": "tx_abc12312345",
"loyalty_system_data": {},
"loyalty_system_id": "",
"loyalty_currency": "LLL",
"metadata": {
"foo": "bar"
},
"origin_account": {
"id": "acc_abc123",
"owner": {
"id": "mp_abc123",
"type": "partner"
}
},
"reason": "present",
"reason_code": "",
"related_data": "",
"release_date": "2447-12-01T21:56:57Z",
"status": "pending",
"status_message": "The release date has not been reached.",
"status_message_code": "release_date_not_reached",
"sub-type": "activity_rule",
"type": "transfer"
}What made this section unhelpful for you?
Retrieve a transaction.
This Endpoint allows you to retrieve the details of a specific transaction.
Path Parameters
Unique internal identifier generated by the system for each transaction.
Response
Response Attributes
The transaction amount in the Loyalty Currency Units
The date and time when this transaction was completed based on the status and release date.
The date and time when this transaction was created. Note that it could be different from when the transaction is completed based on the status and release date.
Represents an account in the system.
Show child attributes
A unique identifier that can be used as a reference to uniquely identify the action in your system.
Unique internal identifier generated by the system for each Transaction.
This parameter requires you to send additional information to connect to the loyalty program. For example, user_id, application_id, partner_code, etc. The Partners Endpoint provides the details on which data fields are mandatory inside this parameter.
Unique transaction identifier provided by the loyalty system.
This unique identifier represents the loyalty program currency to which the member belongs. It is a unique shortcode Identifier assigned by the system to each loyalty currency. It can be found in the 'My Currency' section under the 'About My Currency' screen in the Management Dashboard. For the Currency Identifier of your partners' currencies refer to the Currency Symbol field in the 'My Partners' section in the Management Dashboard or Endpoints to obtain Partners information..
Allows up to 5 levels of nesting depth. This data content can include information about the purchase such as items included, information about the store, information about the member, or anything else that could be helpful for analytics and reporting.
Show child attributes
Represents an account in the system.
Show child attributes
The textual description for why the transaction was created. This text is presented to the origin and destination account holders in their transaction history. While any string length is accepted, 26 characters or less is typically optimal to explain to the member in their transaction history why this transaction was created.
Reason code for why the transaction was created. This field is used for reporting purposes if the ‘reason’ field is dynamic and can vary within one category of transactions.
This provides data about the related action that created the transaction. Actions could be the execution of transaction rule(s), activity rule(s), or a redemption. It is different from Metadata field because Metadata is additional optional information whereas this field is mandatory for certain actions such as Purchase rule, Activity rule, and Redemptions.
Future date on which the Loyalty Currency Units should be made available to the member. The Loyalty Currency Units would be reserved for the member but not made available till the release date is reached. This is used in scenarios such as hotel bookings or flight purchases that are done before the trip so that the member doesn’t redeem the points until they’ve actually stayed at the hotel or flown in the booked flight.
Provides the current status of the transaction. Transactions executed completely have the status set to completed. Refer to the fields status_message_code and status_message for further information if the transaction status is anything other than completed.
adjustedcancelledcompletedpendingpending_external_approvalrejectedreversedThe detailed reason why the transaction is not in the completed status. This field will be null if the transaction status is completed.
The code representing the details about the transaction status when the transaction status is not completed. This field will be null if the transaction status is completed.
release_date_not_reachedpending_external_approvalmember_does_not_existThis field provides further granular information about certain types of transactions.
activity_ruleadjustment_decreaseadjustment_increasebuycancellationinmembermember_to_memberotherout... 5 other enums
A transaction will always have a type associated with it.
accrualgift_card_exchangeloyalty_currency_expirationloyalty_currency_generationloyalty_currency_purchaseloyalty_currency_withdrawalmember_exchangeredemptiontransferreversal... 1 other enums
Response Attributes
Show child attributes
What made this section unhelpful for you?
Response
{
"amount": 250,
"completed_at": "2019-03-04T11:50:03+0000",
"created_at": "2019-03-04T11:50:03+0000",
"destination_account": {
"id": "acc_abc123",
"owner": {
"id": "mp_abc123",
"type": "partner"
}
},
"external_reference": "",
"id": "tx_abc12312345",
"loyalty_system_data": {},
"loyalty_system_id": "",
"loyalty_currency": "LLL",
"metadata": {
"foo": "bar"
},
"origin_account": {
"id": "acc_abc123",
"owner": {
"id": "mp_abc123",
"type": "partner"
}
},
"reason": "present",
"reason_code": "",
"related_data": "",
"release_date": "2447-12-01T21:56:57Z",
"status": "pending",
"status_message": "The release date has not been reached.",
"status_message_code": "release_date_not_reached",
"sub-type": "activity_rule",
"type": "transfer"
}What made this section unhelpful for you?
Update a transaction
This Endpoint allows you to update the details of a specific transaction. A transaction can only be updated if its status is pending and the update is requested either by the owner of the origin account of the transaction or the creator of the transaction.
NOTE: Use the "Adjust a Redemption" Endpoint to refund or modify a Redemption transaction, if permitted by the Currency Owner.
Path Parameters
Unique internal identifier generated by the system for each transaction.
Body Parameters
Amount of loyalty currency units to give.
This parameter requires you to send additional information to connect to the loyalty program. For example, user_id, application_id, partner_code, etc. The Partners Endpoint provides the details on which data fields are mandatory inside this parameter.
Allows up to 5 levels of nesting depth. This data content can include information about the purchase such as items included, information about the store, information about the member, or anything else that could be helpful for analytics and reporting.
Show child attributes
Reason code for why the transaction was created. This field is used for reporting purposes if the ‘reason’ field is dynamic and can vary within one category of transactions.
Textual description for why the transaction was created. This text is presented to the origin and destination account holders in their transaction history. While any string length is accepted, 26 characters or less is typically optimal to explain to the member in their transaction history why this transaction was created.
Future date on which the Loyalty Currency Units should be made available to the member. The Loyalty Currency Units would be reserved for the member but not made available till the release date is reached. This is used in scenarios such as hotel bookings or flight purchases that are done before the trip so that the member doesn’t redeem the points until they’ve actually stayed at the hotel or flown in the booked flight. The transaction will be created with the status as "pending...
Response
Response Attributes
The transaction amount in the Loyalty Currency Units
The date and time when this transaction was completed based on the status and release date.
The date and time when this transaction was created. Note that it could be different from when the transaction is completed based on the status and release date.
Represents an account in the system.
Show child attributes
A unique identifier that can be used as a reference to uniquely identify the action in your system.
Unique internal identifier generated by the system for each Transaction.
This parameter requires you to send additional information to connect to the loyalty program. For example, user_id, application_id, partner_code, etc. The Partners Endpoint provides the details on which data fields are mandatory inside this parameter.
Unique transaction identifier provided by the loyalty system.
This unique identifier represents the loyalty program currency to which the member belongs. It is a unique shortcode Identifier assigned by the system to each loyalty currency. It can be found in the 'My Currency' section under the 'About My Currency' screen in the Management Dashboard. For the Currency Identifier of your partners' currencies refer to the Currency Symbol field in the 'My Partners' section in the Management Dashboard or Endpoints to obtain Partners information..
Allows up to 5 levels of nesting depth. This data content can include information about the purchase such as items included, information about the store, information about the member, or anything else that could be helpful for analytics and reporting.
Show child attributes
Represents an account in the system.
Show child attributes
The textual description for why the transaction was created. This text is presented to the origin and destination account holders in their transaction history. While any string length is accepted, 26 characters or less is typically optimal to explain to the member in their transaction history why this transaction was created.
Reason code for why the transaction was created. This field is used for reporting purposes if the ‘reason’ field is dynamic and can vary within one category of transactions.
This provides data about the related action that created the transaction. Actions could be the execution of transaction rule(s), activity rule(s), or a redemption. It is different from Metadata field because Metadata is additional optional information whereas this field is mandatory for certain actions such as Purchase rule, Activity rule, and Redemptions.
Future date on which the Loyalty Currency Units should be made available to the member. The Loyalty Currency Units would be reserved for the member but not made available till the release date is reached. This is used in scenarios such as hotel bookings or flight purchases that are done before the trip so that the member doesn’t redeem the points until they’ve actually stayed at the hotel or flown in the booked flight.
Provides the current status of the transaction. Transactions executed completely have the status set to completed. Refer to the fields status_message_code and status_message for further information if the transaction status is anything other than completed.
adjustedcancelledcompletedpendingpending_external_approvalrejectedreversedThe detailed reason why the transaction is not in the completed status. This field will be null if the transaction status is completed.
The code representing the details about the transaction status when the transaction status is not completed. This field will be null if the transaction status is completed.
release_date_not_reachedpending_external_approvalmember_does_not_existThis field provides further granular information about certain types of transactions.
activity_ruleadjustment_decreaseadjustment_increasebuycancellationinmembermember_to_memberotherout... 5 other enums
A transaction will always have a type associated with it.
accrualgift_card_exchangeloyalty_currency_expirationloyalty_currency_generationloyalty_currency_purchaseloyalty_currency_withdrawalmember_exchangeredemptiontransferreversal... 1 other enums
Response Attributes
Show child attributes
What made this section unhelpful for you?
Response
{
"amount": 250,
"completed_at": "2019-03-04T11:50:03+0000",
"created_at": "2019-03-04T11:50:03+0000",
"destination_account": {
"id": "acc_abc123",
"owner": {
"id": "mp_abc123",
"type": "partner"
}
},
"external_reference": "",
"id": "tx_abc12312345",
"loyalty_system_data": {},
"loyalty_system_id": "",
"loyalty_currency": "LLL",
"metadata": {
"foo": "bar"
},
"origin_account": {
"id": "acc_abc123",
"owner": {
"id": "mp_abc123",
"type": "partner"
}
},
"reason": "present",
"reason_code": "",
"related_data": "",
"release_date": "2447-12-01T21:56:57Z",
"status": "pending",
"status_message": "The release date has not been reached.",
"status_message_code": "release_date_not_reached",
"sub-type": "activity_rule",
"type": "transfer"
}What made this section unhelpful for you?
Cancel a transaction
This Endpoint allows you to cancel a specific transaction. A transaction can only be canceled if its status is pending and the cancellation is requested either by the owner of the origin account of the transaction or the creator of the transaction.
NOTE: Use the "Adjust a Redemption" Endpoint to refund or modify a Redemption transaction, if permitted by the Currency Owner.
Path Parameters
Unique internal identifier generated by the system for each transaction.
Response
Response Attributes
The transaction amount in the Loyalty Currency Units
The date and time when this transaction was completed based on the status and release date.
The date and time when this transaction was created. Note that it could be different from when the transaction is completed based on the status and release date.
Represents an account in the system.
Show child attributes
A unique identifier that can be used as a reference to uniquely identify the action in your system.
Unique internal identifier generated by the system for each Transaction.
This parameter requires you to send additional information to connect to the loyalty program. For example, user_id, application_id, partner_code, etc. The Partners Endpoint provides the details on which data fields are mandatory inside this parameter.
Unique transaction identifier provided by the loyalty system.
This unique identifier represents the loyalty program currency to which the member belongs. It is a unique shortcode Identifier assigned by the system to each loyalty currency. It can be found in the 'My Currency' section under the 'About My Currency' screen in the Management Dashboard. For the Currency Identifier of your partners' currencies refer to the Currency Symbol field in the 'My Partners' section in the Management Dashboard or Endpoints to obtain Partners information..
Allows up to 5 levels of nesting depth. This data content can include information about the purchase such as items included, information about the store, information about the member, or anything else that could be helpful for analytics and reporting.
Show child attributes
Represents an account in the system.
Show child attributes
The textual description for why the transaction was created. This text is presented to the origin and destination account holders in their transaction history. While any string length is accepted, 26 characters or less is typically optimal to explain to the member in their transaction history why this transaction was created.
Reason code for why the transaction was created. This field is used for reporting purposes if the ‘reason’ field is dynamic and can vary within one category of transactions.
This provides data about the related action that created the transaction. Actions could be the execution of transaction rule(s), activity rule(s), or a redemption. It is different from Metadata field because Metadata is additional optional information whereas this field is mandatory for certain actions such as Purchase rule, Activity rule, and Redemptions.
Future date on which the Loyalty Currency Units should be made available to the member. The Loyalty Currency Units would be reserved for the member but not made available till the release date is reached. This is used in scenarios such as hotel bookings or flight purchases that are done before the trip so that the member doesn’t redeem the points until they’ve actually stayed at the hotel or flown in the booked flight.
Provides the current status of the transaction. Transactions executed completely have the status set to completed. Refer to the fields status_message_code and status_message for further information if the transaction status is anything other than completed.
adjustedcancelledcompletedpendingpending_external_approvalrejectedreversedThe detailed reason why the transaction is not in the completed status. This field will be null if the transaction status is completed.
The code representing the details about the transaction status when the transaction status is not completed. This field will be null if the transaction status is completed.
release_date_not_reachedpending_external_approvalmember_does_not_existThis field provides further granular information about certain types of transactions.
activity_ruleadjustment_decreaseadjustment_increasebuycancellationinmembermember_to_memberotherout... 5 other enums
A transaction will always have a type associated with it.
accrualgift_card_exchangeloyalty_currency_expirationloyalty_currency_generationloyalty_currency_purchaseloyalty_currency_withdrawalmember_exchangeredemptiontransferreversal... 1 other enums
Response Attributes
Show child attributes
What made this section unhelpful for you?
Response
{
"amount": 250,
"completed_at": "2019-03-04T11:50:03+0000",
"created_at": "2019-03-04T11:50:03+0000",
"destination_account": {
"id": "acc_abc123",
"owner": {
"id": "mp_abc123",
"type": "partner"
}
},
"external_reference": "",
"id": "tx_abc12312345",
"loyalty_system_data": {},
"loyalty_system_id": "",
"loyalty_currency": "LLL",
"metadata": {
"foo": "bar"
},
"origin_account": {
"id": "acc_abc123",
"owner": {
"id": "mp_abc123",
"type": "partner"
}
},
"reason": "present",
"reason_code": "",
"related_data": "",
"release_date": "2447-12-01T21:56:57Z",
"status": "pending",
"status_message": "The release date has not been reached.",
"status_message_code": "release_date_not_reached",
"sub-type": "activity_rule",
"type": "transfer"
}What made this section unhelpful for you?
Partners
Partners Endpoints are used to retrieve information about Partners and specific Partnerships with those Partners. These Endpoints provide information such as Company Name, Logos, Loyalty Currency Information, the terms of the partnership(s), actions available, and the required fields for the actions available. This information can be used to drive different UX paths and to automate API calls.